Skip Headers

Oracle® C++ Call Interface Programmer's Guide 10g Release 2 (10.2) Part Number B14294-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# Blob Cl ass

The `Blob` class defines the common properties of objects of type `BLOB`. A `BLOB` is a large binary object stored as a column value in a row of a database table. A `Blob` object contains a logical pointer to a `BLOB`, not the `BLOB` itself.

Methods of the `Blob` class enable you to perform specific tasks related to `Blob` objects.

Methods of the `ResultSet` and `Statement` classes, such as `getBlob()` and `setBlob()`, enable you to access an SQL `BLOB` value.

The only methods valid on a `NULL` `Blob` object are setName(), isNull(), and operator=().

An uninitialized `Blob object` can be initialized by:

- The setEmpty() method. The `BLOB` can then be modified by inserting this `BLOB` into the table and then retrieving it using `SELECT` ... `FOR` `UPDATE`. The write() method will modify the `BLOB`; however, the modified data will be flushed to the table only when the transaction is committed. Note that an update is not required.

- Assigning an initialized `Blob` object to it.

See Also: In-depth discussion of `LOB`s in the introductory chapter of Oracle Database Application Developer's Guide - Large Objects,

Table 12-8 Summary of Blob Methods

Method | Summary
--- | ---
Blob() | `Blob` class constructor.
append() | Appends a specified `BLOB` to the end of the current `BLOB`.
close() | Closes a previously opened `BLOB`.
closeStream() | Closes the `Stream` object obtained from the `BLOB`.
copy() | Copies a specified portion of a `BFILE` or `BLOB` into the current `BLOB`.
getChunkSize() | Returns the chunk size of the `BLOB`.
getStream() | Returns data from the `BLOB` as a `Stream` object.
isInitialized() | Tests whether the `Blob` object is initialized
isNull() | Tests whether the `Blob` object is atomically `NULL`.
isOpen() | Tests whether the `BLOB` is open.
length() | Returns the number of bytes in the `BLOB`.
open() | Opens the `BLOB` `with read or` read/write access.
operator=() | Assigns a `BLOB` locator to the `Blob` object.
operator==() | Tests whether two `Blob` objects are equal.
operator!= () | Tests whether two `Blob` objects are not equal.
read() | Reads a portion of the `BLOB` into a buffer.
setEmpty() | Sets the `Blob` object to empty.
setNull() | Sets the `Blob` object to atomically `NULL`.
trim() | Truncates the `BLOB` to a specified length.
write() | Writes a buffer into an unopened `BLOB`.
writeChunk() | Writes a buffer into an open `BLOB`.

## Blob()

`Blob` class constructor.

Syntax | Description
--- | ---
    Blob();
| Creates a `NULL` `Blob` object.
    Blob(
       const Connection *connectionp);
| Creates an uninitialized `Blob` object.
    Blob(
       const Blob &srcBlob);
| Creates a copy of a `Blob` object.

Parameter | Description
--- | ---
    connectionp
| The connection pointer
    srcBlob
| The source `Blob` object.

## append()

Appends a `BLOB` to the end of the current `BLOB`.

Syntax

    void append(
       const Blob &srcBlob);

Parameter | Description
--- | ---
    srcBlob
| The `BLOB` object to be appended to the current `BLOB` object.

## close()

Closes a `BLOB`.

Syntax

    void close();

## closeStream()

Closes the Stream object obtained from the `BLOB`.

Syntax

    void closeStream(
       Stream *stream);

Parameter | Description
--- | ---
    stream
| The `Stream` to be closed.

## copy()

Copies a part or all of a `BFILE` or `BLOB` into the current `BLOB`.

Syntax | Description
--- | ---
    void copy(
       const Bfile &srcBfile,
       unsigned int numBytes,
       unsigned int dstOffset = 1,
       unsigned int srcOffset = 1);
| Copies a part of a `BFILE` into the current `BLOB`.
    void copy(
       const Blob &srcBlob,
       unsigned int numBytes,
       unsigned int dstOffset = 1,
       unsigned int srcOffset = 1);
| Copies a part of a `BLOB` into the current `BLOB`.

Parameter | Description
--- | ---
    srcBfile
| The `BFILE` from which the data is to be copied.
    srcBlob
| The `BLOB` from which the data is to be copied.
    numBytes
| The number of bytes to be copied from the source `BFILE` or `BLOB`. Valid values are numbers greater than 0.
    dstOffset
| The starting position at which to begin writing data into the current `BLOB`. Valid values are numbers greater than or equal to 1.
    srcOffset
| The starting position at which to begin reading data from the source `BFILE` or `BLOB`. Valid values are numbers greater than or equal to 1.

## getChunkSize()

Returns the chunk size of the `BLOB`. When creating a table that contains a `BLOB`, the user can specify the chunking factor, which can be a multiple of Oracle blocks. This corresponds to the chunk size used by the `LOB` data layer when accessing or modifying the `BLOB`.

Syntax

    unsigned int getChunkSize() const;

## getStream()

Returns a `Stream` object from the `BLOB`. If a stream is already open, it is disallowed to open another stream on `Blob object`, so the user must always close the stream before performing any `Blob` object operations.

Syntax

    Stream* getStream(
       unsigned int offset = 1,
       unsigned int amount = 0);

Parameter | Description
--- | ---
    offset
| The starting position at which to begin reading data from the `BLOB`. If `offset` is not specified, the data is written from the beginning of the `BLOB`. Valid values are numbers greater than or equal to `1`.
    amount
| The total number of bytes to be read from the `BLOB`; if `amount` is `0`, the data will be read in a streamed mode from input `offset` until the end of the `BLOB`.

## isInitialized()

Tests whether the `Blob` object is initialized. If the `Blob` object is initialized, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool isInitialized() const;

## isNull()

Tests whether the `Blob` object is atomically `NULL`. If the `Blob` object is atomically `NULL`, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool isNull() const;

## isOpen()

Tests whether the `BLOB` is open. If the `BLOB` is open, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool isOpen() const;

## length()

Returns the number of bytes in the `BLOB`.

Syntax

    unsigned int length() const;

## open()

Opens the `BLOB` in read/write or read-only mode.

Syntax

    void open(
       LobOpenMode mode = OCCI_LOB_READWRITE);

Parameter | Description
--- | ---
    mode
| The mode the `BLOB` is to be opened in. Valid values are: `OCCI_LOB_READWRITE` `OCCI_LOB_READONLY`

## operator=()

Assigns a `BLOB` to the current `BLOB`. The source `BLOB` gets copied to the destination `BLOB` only when the destination `BLOB` gets stored in the table.

Syntax

    Blob& operator=(
       const Blob &srcBlob);

Parameter | Description
--- | ---
    srcBlob
| The source `BLOB` from which to copy data.

## operator==()

Compares two `Blob objects` for equality. Two `Blob objects` are equal if they both refer to the same `BLOB`. Two `NULL` `Blob objects` are not considered equal. If the `Blob` objects are equal, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool operator==(
       const Blob &srcBlob) const;

Parameter | Description
--- | ---
    srcBlob
| The source `BLOB` to be compared with the current `BLOB`.

## operator!= ()

Compares two `Blob objects` for inequality. Two `Blob objects` are equal if they both refer to the same `BLOB`. Two `NULL` `Blob` objects are not considered equal. If the `Blob` objects are not equal, then `TRUE` is returned; otherwise, `FALSE` is returned.

Syntax

    bool operator!=(
       const Blob &srcBlob) const;

Parameter | Description
--- | ---
    srcBlob
| The source `BLOB` to be compared with the current `BLOB`.

## read()

Reads a part or all of the `BLOB` into a buffer. The actual number of bytes read is returned.

Syntax

    unsigned int read(
       unsigned int amt,
       unsigned char *buffer,
       unsigned int bufsize,
       unsigned int offset = 1) const;

Parameter | Description
--- | ---
    amt
| The number of bytes to be read. Valid values are numbers greater than or equal to `1`.
    buffer
| The buffer that the `BLOB` data is to be read into. Valid values are numbers greater than or equal to `amt`.
    buffsize
| The size of the buffer that the `BLOB` data is to be read into. Valid values are numbers greater than or equal to `amt`.
    offset
| The starting position at which to begin reading data from the `BLOB`. If `offset` is not specified, the data is written from the beginning of the `BLOB`.

## setEmpty()

Sets the `Blob` object to empty.

Syntax | Description
--- | ---
    void setEmpty();
| Sets the `Blob` object to empty.
    void setEmpty(
       const Connection* connectionp);
| Sets the `Blob` object to empty and initializes the connection pointer to the passed parameter.

Parameter | Description
--- | ---
    connectionp
| The new connection pointer for the `BLOB` object.

## setNull()

Sets the `Blob` object to atomically `NULL`.

Syntax

    void setNull();

## trim()

Truncates the `BLOB` to the new length specified.

Syntax

    void trim(
       unsigned int newlen);

Parameter | Description
--- | ---
    newlen
| The new length of the `BLOB`. Valid values are numbers less than or equal to the current length of the `BLOB`.

## write()

Writes data from a buffer into a `BLOB`. This method implicitly opens the `BLOB`, copies the buffer into the `BLOB`, and implicitly closes the `BLOB`. If the `BLOB` is already open, use writeChunk() instead. The actual number of bytes written is returned.

Syntax

    unsigned int write(
       unsigned int amt,
       unsigned char *buffer,
       unsigned int bufsize,
       unsigned int offset = 1);

Parameter | Description
--- | ---
    amt
| The number of bytes to be written to the `BLOB`.
    buffer
| The buffer containing the data to be written to the `BLOB`.
    buffsize
| The size of the `buffer containing the data to be written to the` `BLOB``.` Valid values are numbers greater than or equal to `amt`.
    offset
| The starting position at which to begin writing data into the `BLOB`. If `offset` is not specified, the data is written from the beginning of the `BLOB`. Valid values are numbers greater than or equal to 1.

## writeChunk()

Writes data from a buffer into a previously opened `BLOB`. The actual number of bytes written is returned.

Syntax

    unsigned int writeChunk(
       unsigned int amount,
       unsigned char *buffer,
       unsigned int bufsize,
       unsigned int offset = 1);

Parameter | Description
--- | ---
    amt
| The number of bytes to be written to the `BLOB`.
    buffer
| The buffer containing the data to be written to the `BLOB`.
    buffsize
| The size of the buffer containing the data to be written to the `BLOB`. Valid values are numbers greater than or equal to `amt`.
    offset
| The starting position at which to begin writing data into the `BLOB`. If `offset` is not specified, the data is written from the beginning of the `BLOB`. Valid values are numbers greater than or equal to `1`.